From blank to HTML

Artwork by @allison_horst, CC-BY 4.0

1 Basics

1.1 Text and Code

This is an R Markdown document. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see http://rmarkdown.rstudio.com.

You can embed an R code chunk like this:

summary(cars)

##      speed           dist       
##  Min.   : 4.0   Min.   :  2.00  
##  1st Qu.:12.0   1st Qu.: 26.00  
##  Median :15.0   Median : 36.00  
##  Mean   :15.4   Mean   : 42.98  
##  3rd Qu.:19.0   3rd Qu.: 56.00  
##  Max.   :25.0   Max.   :120.00

Ok, let’s pause a second a talk about chunks. We’ve just run an R chunk. We did this by opening the chunk with ```, writing {r} after the three backticks that open the chunk, then wrote our code, and finally closed the chunk with ```.

Remember, be a

Artwork by @allison_horst, CC-BY 4.0

We can also set a number of options in this way. To set options, you write [option name]=[value] after writing ```{r} Some popular options:

• include, should the chunk be part of the output or not? [TRUE or FALSE]
• echo, to show or hide the code in the output [TRUE or FALSE]
• tidyr, to tidy the appearance of the code in the output [TRUE or FALSE]

You can find all rmarkdown code chunk options in this handy pdf cheatsheet, alongside a description of what values they can take and what do they do to your code.

1.2 Including Plots and Figure

You can also embed plots, for example:

plot(pressure)

Note that the echo = FALSE parameter was added to the code chunk to prevent printing of the R code that generated the plot.

What if I add two plots in the same chunk?

plot(pressure)
title(main = "A classic plot")

ggplot(data = pressure, aes(x = temperature, y = pressure)) + geom_point() + ggtitle("A fancier plot") + 
    theme_classic()

And what about including an external image?

knitr::include_graphics("/Users/matteo/stats-illustrations/rstats-artwork/r_rollercoaster.png")

Artwork by @allison_horst, CC-BY 4.0

1.3 What about Tables and data frames?

Well, that depends. If it is a simple table, you can just type it out. For instance:

Variable	Description	Units	Range
Ni	Nutrients stocks in patch i	g	>0
Pi	Producers stocks in patch i	g	>0
Ci	Consumers stocks in patch i	g	>0

Of course, just as you can embed plots, you can also embed more complex tables and data frames:

pressure

Or, to be a bit fancier, one can use function kable and the kableExtra package:

library(kableExtra)

## 
## Attaching package: 'kableExtra'

## The following object is masked from 'package:dplyr':
## 
##     group_rows

kable(pressure) %>% kable_styling(bootstrap_options = c("striped", "hover", "condensed"), 
    fixed_thead = TRUE) %>% scroll_box(width = "100%", height = "150px")

temperature	pressure
0	0.0002
20	0.0012
40	0.0060
60	0.0300
80	0.0900
100	0.2700
120	0.7500
140	1.8500
160	4.2000
180	8.8000
200	17.3000
220	32.1000
240	57.0000
260	96.0000
280	157.0000
300	247.0000
320	376.0000
340	558.0000
360	806.0000

1.4 References and Bibliographies

Alright, you got your code, you got your text, your got your fancy swanky plots. However, we all know it’s not a real piece of scientific writing if there is not at least one however and several references (and a double negative, if you’re Anne).

So, references. R Markdown relies on a similarly plain-text format to deal with these: BibTeX. Essentially, the workflow is this:

1.4.1 Step 1

You create a text file, save it with .bib extension in the same directory as your .Rmd file

1.4.2 Step 2

Start populating it with citations: all journals/search engines allow you to export BibTeX formatted citations, and several free pieces of software exist to help you manage them (I prefer to do it by hand).

A typical BibTex entry looks like this:

@article{allaire2018,
  title={rmarkdown: Dynamic Documents for R},
  author={Allaire, J and Xie, Yihui and McPherson, Jonathan and Luraschi, Javier and Ushey, Kevin and Atkins, Aron and Wickham, Hadley and Cheng, Joe and Chang, Winston and Iannone, Richard},
  journal={R package version},
  volume={1},
  number={11},
  year={2018}
}

1.4.3 Step 3

Now come back to your R Markdown document. We need to tell R Markdown that we have a bibliography file (.bib), that we want R Markdown to use it when we will hit the Knit button, and that some of the words in our text are going to be references. How do we do all this?

First things first. We go back to the YAML metadata at the very top and we add this new item to the list of options:

bibliography: rmarkdowntourbibliography.bib

This tells R Markdown two things: (i) that we are going to insert references in the text we are going to write and (ii) that when we hit Knit, we want R Markdown to go look for that .bib file to find the references.

Now, to add the references to the text itself.

1.4.4 Step 4

Whenever and wherever you’d like to add a citation, you type [@citationkey]. citationkey is BibTeX code, and it is a unique identifier for each item in a .bib file.

Using the reference I showed you above, I type [@allaire2018] and it produces (Allaire et al. 2018). If you scroll to the bottom, you’ll find a complete citation for it.

Now, R Markdown is smart but not *that* smart, so it will not create a section header for your references/bibliography/literature cited section. Don’t forget to add it yourself at the very end of your document!

1.5 Writing, Running, Knitting… what?

Alright, well, now that we’ve done all this stuff, it would be nice to see the final product, wouldn’t it?

Getting to the cool-looking HTML output is easy-peasy: look at the top of this tab. You’ll see a little icon showing a blue yarn stabbed by a needles, with the label “Knit” next to it.

When you click the Knit button a document will be generated that includes both content as well as the output of any embedded R code chunks within the document.

References

Allaire, J, Yihui Xie, Jonathan McPherson, Javier Luraschi, Kevin Ushey, Aron Atkins, Hadley Wickham, Joe Cheng, Winston Chang, and Richard Iannone. 2018. “Rmarkdown: Dynamic Documents for r.” R Package Version 1 (11).